home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 027a / clip5not.zip / MAN500.TXT next >
Text File  |  1990-10-08  |  11KB  |  303 lines
  1.  
  2.  DECLARE*       Create and initialize private memory variables and arrays
  3.  DECLARE*
  4.  Create and initialize private memory variables and arrays
  5.  
  6.  Syntax: DECLARE <identifier> [[:= <initializer>], ... ]
  7.  
  8.  Arguments
  9.  
  10.      <identifier> is the name of a private variable or array to create.
  11.      If the <identifier> is followed by square brackets ([ ]), it is created
  12.      as an array.  If the <identifier> is an array, the syntax for
  13.      specifying the number of elements for each dimension is either
  14.      array[<nElements>, <nElements2>,...] or
  15.      array[<nElements>][<nElements2>]...  The maximum number of elements per
  16.      dimension is 4096.
  17.  
  18.      <initializer> is the optional assignment of a value to a new
  19.      private variable.  An <initializer> for a private variable consists of
  20.      the in-line assignment operator (:=) followed by any valid Clipper
  21.      expression, including a literal array.  If no explicit <initializer> is
  22.      specified, the variable is given an initial value of NIL.  In the case
  23.      of an array, each element is NIL.  Array identifiers, cannot be given
  24.      values with an <initializer>.
  25.  
  26.      A list of variables or arrays can be created and optionally initialized
  27.      with one DECLARE statement if each definition is separated by a comma.
  28.  
  29.  Description
  30.  
  31.      DECLARE is a compatibility statement that is a synonym for the PRIVATE
  32.      statement.  Its general use is not recommended.  PRIVATE should be used
  33.      in all instances.  See PRIVATE for more information.
  34.  
  35.  
  36.  FIELDBLOCK()
  37.  Return a set-get code block for a field variable
  38.  
  39.  Syntax: FIELDBLOCK(<cFieldName>) --> bFieldBlock
  40.  
  41.  Arguments
  42.  
  43.      <cFieldName> is the name of the field the set-get block will refer to.
  44.  
  45.  Returns
  46.  
  47.      FIELDBLOCK() returns a code block the when evaluated sets (assigns) or
  48.      gets (retrieves) the value of the given field.  If <cFieldName> does
  49.      not exist in the current work area, FIELDBLOCK() returns NIL.
  50.  
  51.  Description
  52.  
  53.      FIELDBLOCK() is a database function that builds a code block.  When
  54.      executed with a argument, the code block created by this function
  55.      assigns the value of the argument to <cFieldName>.  When executed
  56.      without a argument, the code block retrieves the value of <cFieldName>.
  57.  
  58.  Notes
  59.  
  60.        Work Area: The code block returned by FIELDBLOCK() sets
  61.         or gets the value of the specified field in whatever work area is
  62.         current when the block is run.  For example, given work areas 1 and
  63.         2, both containing field FName:
  64.  
  65.         SELECT 1
  66.         FName:= "Kate"
  67.         SELECT 2
  68.         FName := "Cindy"
  69.  
  70.         bFName := FIELDBLOCK("FName")
  71.  
  72.         SELECT 1
  73.         ? EVAL(bFName)      // "Kate"
  74.         SELECT 2
  75.         ? EVAL(bFName)      // "Cindy"
  76.  
  77.         The function FIELDWBLOCK() provides a set-get block for a field in a
  78.         specific work area.
  79.  
  80.  Examples
  81.  
  82.      The following example compares FIELDBLOCK() to a code block created
  83.      using the macro operator.  Note that using FIELDBLOCK() allows you to
  84.      avoid the speed and size overhead of the macro operator:
  85.  
  86.      // Set-Get block defined using macro operator
  87.      bSetGet := &( "{ |setVal| IF( setVal == NIL, FName, FName := setVal ) }" )
  88.  
  89.      // Set-Get block defined using FIELDBLOCK()
  90.      // bSetGet created here is the functional equivalent of bSetGet above
  91.      bSetGet := FIELDBLOCK("FName")
  92.  
  93.  Files:  Library is CLIPPER.LIB.
  94.  seealso: "FIELDWBLOCK()" "MEMVARBLOCK()"
  95.  
  96.  
  97.  FIELDGET()
  98.  Retrieve the value of a field using the ordinal position of the
  99.  field in the database structure
  100.  
  101.  Syntax: FIELDGET(<nField>) --> valueField
  102.  
  103.  Arguments
  104.  
  105.      <nField>is the ordinal position of the field in the record
  106.      structure for the current work area.
  107.  
  108.  Returns
  109.  
  110.      FIELDGET() returns the value of the specified field.  If <nField> does
  111.      not correspond to the position of any field in the current database
  112.      file, FIELDGET() returns NIL.
  113.  
  114.  Description
  115.  
  116.      FIELDGET() is a database function that retrieves the value of a field
  117.      using its position within the database file structure rather than its
  118.      field name.  Within generic database service functions this allows,
  119.      among other things, the retrieval of field values without use of the
  120.      macro operator.
  121.  
  122.  Examples
  123.  
  124.      The following example compares FIELDGET() to functionally equivalent
  125.      code that uses the macro operator to retrieve the value of a field:
  126.  
  127.      LOCAL nField := 1, FName, FVal
  128.      USE Customer NEW
  129.      //
  130.      // Using macro operator
  131.      FName := FIELD( nField )        // Get field name
  132.      FVal := &FName                  // Get field value
  133.  
  134.      // Using FIELDGET()
  135.      FVal := FIELDGET( nField )      // Get field value
  136.  
  137.  Files:  Library is CLIPPER.LIB.
  138.  seealso: "FIELDPUT()"
  139.  
  140.  
  141.  FIELDPUT()     Set the value of a field variable
  142.  FIELDPUT()
  143.  Set the value of a field variable using the ordinal position of
  144.  the field in the database structure
  145.  
  146.  Syntax: FIELDPUT(<nField>, <expAssign>) --> valueAssigned
  147.  
  148.  Arguments
  149.  
  150.      <nField> is the ordinal position of the field in the current
  151.      database file.
  152.  
  153.      <expAssign> is the value to assign to the given field.  The data
  154.      type of this expression must match the data type of the designated
  155.      field variable.
  156.  
  157.  Returns
  158.  
  159.      FIELDPUT() returns the value assigned to the designated field.  If
  160.      <nField> does not correspond to the position of any field in the
  161.      current database file, FIELDPUT() returns NIL.
  162.  
  163.  Description
  164.  
  165.      FIELDPUT() is a database function that assigns <expAssign> to the field
  166.      at ordinal position <nField> in the current work area.  This function
  167.      allows you to set the value of a field using its position within the
  168.      database file structure rather than its field name.  Within generic
  169.      database service functions this allows, among other things, the setting
  170.      of field values without use of the macro operator.
  171.  
  172.  Examples
  173.  
  174.      The following example compares FIELDPUT() to functionally equivalent
  175.      code that uses the macro operator to retrieve the value of a field:
  176.  
  177.      // Using macro operator
  178.      FName := FIELD(nField)       // Get field name
  179.      FIELD->&FName := FVal        // Set field value
  180.  
  181.      // Using FIELDPUT()
  182.      FIELDPUT(nField, FVal)       // Set field value
  183.  
  184.  Files:  Library is CLIPPER.LIB.
  185.  seealso: "FIELDGET()"
  186.  
  187.  
  188.  FIELDWBLOCK()  Return a set-get block for a field in a given work area
  189.  FIELDWBLOCK()
  190.  Return a set-get code block for a field in a given work area
  191.  
  192.  Syntax: FIELDWBLOCK(<cFieldName>, <nWorkArea>) --> bFieldWBlock
  193.  
  194.  Arguments
  195.  
  196.      <cFieldName> is the name of the field the set-get block will refer
  197.      to specified as a character string.
  198.  
  199.      <nWorkArea> is the work area number where the field resides
  200.      specified as a numeric value.
  201.  
  202.  Returns
  203.  
  204.      FIELDWBLOCK() returns a code block that when evaluated sets (assigns)
  205.      or gets (retrieves) the value of <cFieldName> in the work area
  206.      designated by <nWorkArea>.  If <cFieldName> does not exist in the
  207.      specified work area, FIELDWBLOCK() returns NIL.
  208.  
  209.  Description
  210.  
  211.      FIELDWBLOCK() is a database function that builds a code block.  When
  212.      evaluated with the EVAL() function, the code block first selects the
  213.      designated <nWorkArea>.  If an argument was passed, the code block then
  214.      assigns the value of the argument to <cFieldName>.  If no argument was
  215.      passed, the code block retrieves the value of <cFieldName>.  The
  216.      original work area is then re-selected before the code block returns
  217.      control.
  218.  
  219.  Notes
  220.  
  221.        FIELDWBLOCK() is similar to FIELDBLOCK(), the difference
  222.         being that FIELDBLOCK() does not incorporate a fixed work area into
  223.         the set-get block.
  224.  
  225.  Examples
  226.  
  227.        The following example compares FIELDWBLOCK() to a code block
  228.         created using the macro operator.  Note that using FIELDWBLOCK()
  229.         allows you to avoid the speed and size overhead of the macro
  230.         operator:
  231.  
  232.         // Set-Get block for work area 1 defined with macro operator
  233.         bSetGet := &( "{ |setVal| IF( setVal == NIL, ;
  234.            1->FName, 1->FName := setVal ) }" )
  235.  
  236.         // Set-Get block defined using FIELDWBLOCK()<R>
  237.         // bSetGet created here is the functional equivalent of bSetGet above
  238.         bSetGet := FIELDWBLOCK("FName", 1)
  239.  
  240.        Another example of FIELDWBLOCK() can be found in TbDemo.prg,
  241.         a sample program included with Clipper 5.0.  The TBColumn object,
  242.         one of which represents each column in a TBrowse object, requires
  243.         among its instance variables a block to retrieve the expression to
  244.         be displayed.  FIELDWBLOCK() is used to create this block.  In the
  245.         default installation, TbDemo.prg is located in the \CLIPPER5\SOURCE
  246.         directory.
  247.  
  248.  Files:  Library is CLIPPER.LIB.
  249.  seealso: "FIELDBLOCK()" "MEMVARBLOCK()"
  250.  
  251.  
  252.  MEMVARBLOCK()  Return a set-get code block for a given memory variable
  253.  MEMVARBLOCK()
  254.  Return a set-get code block for a given memory variable
  255.  
  256.  Syntax: MEMVARBLOCK(<cMemvarName>) --> bMemvarBlock
  257.  
  258.  Arguments
  259.  
  260.      <cMemvarName> is the name of the variable the set-get block will
  261.      refer to specified as a character string.
  262.  
  263.  Returns
  264.  
  265.      MEMVARBLOCK() returns a code block that when evaluated sets (assigns)
  266.      or gets (retrieves) the value of the given memory variable.  If
  267.      <cMemvarName> does not exist, MEMVARBLOCK() returns NIL.
  268.  
  269.  Description
  270.  
  271.      The code block created by MEMVARBLOCK() has two operations depending on
  272.      whether an argument is passed to the code block when it is evaluated.
  273.      If evaluated with an argument, it assigns the value of the argument to
  274.      <cMemvarName>.  If evaluated without an argument, the code block
  275.      retrieves the value of <cMemvarName>.
  276.  
  277.  Notes
  278.  
  279.        MEMVARBLOCK() creates set-get blocks only for variables
  280.        whose names are known at runtime.  MEMVARBLOCK(), therefore, cannot
  281.        be used to create set-get blocks for local or static variables.  The
  282.        same restriction applies to creating blocks using the macro (&)
  283.        operator.
  284.  
  285.  Examples
  286.  
  287.      The following example compares MEMVARBLOCK() to a code block created
  288.      using the macro (&) operator.  Note that using MEMVARBLOCK() allows you
  289.      to avoid the speed and size overhead of the macro operator:
  290.  
  291.      PRIVATE var := "This is a string"
  292.      //
  293.      // Set-Get block defined using macro operator
  294.      bSetGet := &( "{ |setVal| IF( setVal == NIL, var, var := setVal ) }" )
  295.  
  296.      // Set-Get block defined using MEMVARBLOCK()
  297.      // bSetGet created here is the functional equivalent of bSetGet above
  298.      bSetGet := MEMVARBLOCK("var")
  299.  
  300.  Files:  Library is CLIPPER.LIB.
  301.  seealso: "FIELDBLOCK()" "FIELDWBLOCK()"
  302.  
  303.